lib/content/getArtistRootPrefix.ts (1)

1-5: Make the JSDoc actionable, not just present.

Good addition, but this block currently only repeats parameter names. Please include short descriptions and return semantics so callers understand fallback behavior quickly.

Suggested JSDoc upgrade

 /**
- *
- * `@param` paths
- * `@param` artistSlug
+ * Selects the root prefix used for an artist's content paths.
+ *
+ * Prefers `artists/{artistSlug}/` when present in `paths`, otherwise falls back
+ * to `{artistSlug}/`, and defaults to `artists/{artistSlug}/` if no match exists.
+ *
+ * `@param` paths Candidate content paths to inspect.
+ * `@param` artistSlug Artist slug used to build candidate prefixes.
+ * `@returns` The chosen root prefix for downstream path construction.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/getArtistRootPrefix.ts` around lines 1 - 5, Update the JSDoc for
getArtistRootPrefix: add brief descriptions for the parameters (describe what
"paths" contains and what "artistSlug" represents) and document the return value
and fallback behavior (what string is returned on success and what is returned
when no matching path is found). Reference the function name getArtistRootPrefix
and explicitly mention the expected shape or examples for "paths" and any
edge-cases (empty arrays, undefined artistSlug) so callers know how to handle
failures.

lib/content/isCompletedRun.ts (1)

8-11: Replace placeholder JSDoc with meaningful documentation (or remove it).

This block currently adds little value. Please include a short summary plus precise @param/@returns descriptions so the comment improves maintainability.

As per coding guidelines, "KISS: Prefer simple, readable implementations over clever optimizations."

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/isCompletedRun.ts` around lines 8 - 11, Replace the placeholder
JSDoc above the isCompletedRun function with a concise summary and precise tags:
add a one-line description (e.g., "Determine whether a Run is completed"), an
`@param` {Run} run describing expected properties used (e.g., status, finishedAt)
and any accepted shapes, and an `@returns` {boolean} explaining true means the run
is completed and under what conditions; ensure the doc matches the
isCompletedRun implementation and types referenced in the function signature.

lib/supabase/song_artists/insertSongArtists.ts (1)

9-10: Complete the @param documentation for clarity.

@param songArtists is currently undocumented beyond the name. Add a short description so generated docs and editor hints are actionable.

Suggested JSDoc update

 /**
  * Inserts song-artist relationships, skipping duplicates.
  *
- * `@param` songArtists
+ * `@param` songArtists Array of song-artist join records to validate, deduplicate, and upsert.
  */

As per coding guidelines, “Supabase database functions should import from @/lib/supabase/serverClient and follow the documented pattern with JSDoc comments, error handling, and return types.”

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/supabase/song_artists/insertSongArtists.ts` around lines 9 - 10, Update
the JSDoc for the insertSongArtists function by adding a clear description for
the `@param` songArtists entry (e.g., "array of song-artist relationship objects
to insert, each with song_id and artist_id"), and ensure the comment includes
the expected shape of each item; keep the existing JSDoc tags for return and
throws intact and follow the Supabase pattern used in this file (import from
`@/lib/supabase/serverClient` and proper error handling in insertSongArtists) so
editor/docs show the parameter shape and intent.

lib/content/getArtistFileTree.ts (2)

7-9: Clarify JSDoc parameter intent.

Good addition of @param tags, but these should include short descriptions (and expected format) so IDE/tooling hints are actually useful, e.g. repo URL/name format and slug format.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/getArtistFileTree.ts` around lines 7 - 9, Update the JSDoc for
the getArtistFileTree function to add short descriptions and expected formats
for the `@param` tags: describe githubRepo (e.g., repository owner/name or full
GitHub URL) and artistSlug (e.g., URL-safe lowercase identifier, permitted
characters), so IDE/tooling can show the intended input shape; keep descriptions
concise and consistent with existing project conventions.

---

17-20: Extract duplicate artist-path matching logic into a helper.

The blobPaths + hasArtist computation is repeated in two branches. Pulling this into a small local utility would reduce duplication and keep the function easier to evolve.

As per coding guidelines, "DRY: Consolidate similar logic into shared utilities".

Also applies to: 28-31

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/getArtistFileTree.ts` around lines 17 - 20, Extract the repeated
blob path / artist-match logic inside getArtistFileTree into a small local
helper (e.g., hasArtistInTree or getBlobPathsAndHasArtist) that accepts the tree
array (mainTree) and artistSlug and returns the blobPaths and/or boolean
hasArtist; replace both duplicated blocks that compute blobPaths and hasArtist
with calls to this helper so both branches reuse the same logic and avoid
duplication.

lib/ai/isEmbedModel.ts (2)

6-7: Complete the @param annotation with a description.

The @param m tag is missing a description. JSDoc best practice requires parameter documentation to include both the name and a description of what the parameter represents.

📝 Proposed fix to complete the documentation

 *
-* `@param` m
+* `@param` m - The gateway language model entry to check
 */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/ai/isEmbedModel.ts` around lines 6 - 7, The JSDoc for the isEmbedModel
function is missing a description for the `@param` m tag; update the JSDoc above
the isEmbedModel function (reference symbol: isEmbedModel) to include a brief
description of parameter m (e.g., "the model identifier or object to check") so
the `@param` line documents what m represents and its expected type/format.

---

16-16: Remove redundant default export.

The function is already exported as a named export on line 9. Having both named and default exports of the same function creates ambiguity about the preferred import pattern and adds unnecessary complexity.

♻️ Proposed fix to simplify exports

-
-export default isEmbedModel;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/ai/isEmbedModel.ts` at line 16, Remove the redundant default export for
isEmbedModel: keep the existing named export (export function isEmbedModel ...)
and delete the trailing "export default isEmbedModel;" statement; then search
for any consumers importing the default and update them to the named import {
isEmbedModel } to ensure a single, unambiguous export pattern.

lib/trigger/triggerCreateContent.ts (1)

19-20: Enhance the JSDoc parameter documentation.

The @param tag was added but lacks a description. Consider adding a brief explanation of what the payload contains, and include a @returns tag to document the returned handle.

📝 Suggested JSDoc enhancement

 /**
  * Triggers the create-content task in Trigger.dev.
  *
- * `@param` payload
+ * `@param` payload - The content creation parameters including account, artist, template, and generation options.
+ * `@returns` A handle to the triggered task that can be used to track execution.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/trigger/triggerCreateContent.ts` around lines 19 - 20, Update the JSDoc
for the triggerCreateContent function: add a brief description for the payload
parameter (what fields it contains and their purpose, e.g., content data,
metadata, userId) and add a `@returns` tag describing the handle returned (type
and what it represents, e.g., Promise<Handle> or created content ID/URL). Ensure
the tags reference the existing parameter name "payload" and the function
"triggerCreateContent" so maintainers can quickly understand inputs and outputs.

lib/chat/toolChains/getPrepareStepResult.ts (1)

15-16: Nice documentation addition!

Adding the @param tag improves the JSDoc completeness. For even better developer experience, consider adding a brief description to explain the parameter's purpose.

📝 Optional enhancement for more descriptive JSDoc

  *
- * `@param` options
+ * `@param` options - Configuration containing steps, model, messages, and step number for determining the next tool in the chain
  */

Alternatively, you could document the individual properties if you want more detail:

  *
- * `@param` options
+ * `@param` options - The step preparation options
+ * `@param` options.steps - Array of previous step results with tool executions
+ * `@param` options.stepNumber - Current step number in the conversation
+ * `@param` options.model - The language model being used
+ * `@param` options.messages - Array of conversation messages
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/chat/toolChains/getPrepareStepResult.ts` around lines 15 - 16, Update the
JSDoc for getPrepareStepResult to add a brief description for the `@param` options
entry (and optionally document its key properties) so callers understand what
the options object controls; locate the JSDoc above the getPrepareStepResult
function and add one-line text describing the purpose of options (e.g., what
values it holds and how it affects the function), and if helpful, add short
`@param` entries for specific properties of options referenced in the function.

lib/flamingo/getFlamingoPresetsHandler.ts (1)

13-13: Complete the JSDoc @param annotation with a description.

The @param request tag is missing a description. JSDoc best practice is to include a brief description after the parameter name to provide context in IDE tooltips and generated documentation.

📝 Suggested fix for complete documentation

- * `@param` request
+ * `@param` request - The incoming Next.js HTTP request

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/flamingo/getFlamingoPresetsHandler.ts` at line 13, Add a brief
descriptive text to the JSDoc `@param request` tag for the
getFlamingoPresetsHandler function so IDE tooltips and generated docs show
context; locate the JSDoc block above the getFlamingoPresetsHandler function and
change the `@param request` line to include a short description of what
`request` represents (e.g., incoming HTTP request or handler input) and any
important details such as expected properties or type.

lib/coding-agent/parseMergeActionId.ts (1)

4-11: Complete the JSDoc documentation and add explicit return type.

The @param annotation was added but lacks a description. Additionally, the function is missing a @returns tag and an explicit return type annotation. While TypeScript can infer the return type, explicitly declaring it improves both documentation and type safety.

📝 Proposed enhancements for documentation completeness

 /**
  * Parses a merge action ID like "merge_pr:recoupable/api#42"
  * into { repo, number } or null if the format doesn't match.
  *
- * `@param` actionId
+ * `@param` actionId - The action ID string to parse
+ * `@returns` An object with repo and PR number, or null if format is invalid
  */
-export function parseMergeActionId(actionId: string) {
+export function parseMergeActionId(
+  actionId: string
+): { repo: string; number: number } | null {
   const match = actionId.match(/^merge_pr:(.+)#(\d+)$/);
   if (!match) return null;
   return { repo: match[1], number: parseInt(match[2], 10) };
 }

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/coding-agent/parseMergeActionId.ts` around lines 4 - 11, Update the JSDoc
for parseMergeActionId to document the parameter and return value and add an
explicit return type on the function signature: describe the actionId parameter
(e.g., "actionId - string in the form 'merge_pr:<repo>#<number>'"), add a
`@returns` tag explaining that it returns an object with repo and number or null
on no match, and change the signature of parseMergeActionId(actionId: string) to
explicitly return { repo: string; number: number } | null.

lib/coding-agent/parseMergeTestToMainActionId.ts (1)

4-12: Complete the JSDoc documentation and add explicit return type.

The @param annotation was added but lacks a description. Additionally, the function is missing a @returns tag and an explicit return type annotation, which would improve both documentation clarity and TypeScript type safety.

📝 Proposed enhancements for documentation completeness

 /**
  * Parses a merge_test_to_main action ID like "merge_test_to_main:recoupable/api"
  * into the repo string, or null if the format doesn't match.
  *
- * `@param` actionId
+ * `@param` actionId - The action ID string to parse
+ * `@returns` The repository string (e.g., "owner/repo") or null if format is invalid
  */
-export function parseMergeTestToMainActionId(actionId: string): string | null {
+export function parseMergeTestToMainActionId(actionId: string): string | null {

Note: The explicit return type annotation is already present, so only the JSDoc enhancements are needed.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/coding-agent/parseMergeTestToMainActionId.ts` around lines 4 - 12, Update
the JSDoc for parseMergeTestToMainActionId to describe the parameter and return
value: add a brief description for `@param` actionId (e.g., "the action identifier
to parse, expected to start with 'merge_test_to_main:'") and add an `@returns` tag
that explains the function returns the repository string in "owner/name" format
or null if the prefix is missing or the repo is malformed; keep the existing
explicit return type string | null and ensure the top-level description
summarizes what the function does.

lib/catalog/getCatalogs.ts (1)

11-14: Complete the JSDoc parameter description.

The @param accountId tag lacks a description. Document what account ID is used for to provide clarity.

📝 Suggested JSDoc improvement

 /**
- *
- * `@param` accountId
+ * Fetches all catalogs for a given account
+ *
+ * `@param` accountId - The unique identifier of the account whose catalogs to fetch
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/catalog/getCatalogs.ts` around lines 11 - 14, Update the JSDoc for the
getCatalogs function to describe the accountId parameter: replace the bare
"@param accountId" with a short description such as "the unique identifier of
the account whose catalogs should be retrieved" (or similarly precise wording)
so readers know which account the function will query; ensure the description
mentions expected format (e.g., numeric or UUID) if applicable and keep it
adjacent to the getCatalogs function declaration.

lib/catalog/formatCatalogSongsAsCSV.ts (1)

5-6: Complete the JSDoc parameter description.

The @param songs tag lacks a description. JSDoc parameters should explain what the parameter represents and its purpose to be useful for developers.

📝 Suggested JSDoc improvement

 /**
  * Formats catalog songs into the CSV-like format expected by the scorer
  *
- * `@param` songs
+ * `@param` songs - Array of catalog songs to format as CSV
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/catalog/formatCatalogSongsAsCSV.ts` around lines 5 - 6, The JSDoc for the
function formatCatalogSongsAsCSV is missing a description for the `@param` songs
tag; update the JSDoc to describe what songs is (e.g., an array of song
objects), what each element contains (fields used by the function such as title,
artist, album, duration, etc.), and any expectations (non-empty array, optional
fields), so maintainers know the input shape and constraints expected by
formatCatalogSongsAsCSV; reference the function name formatCatalogSongsAsCSV and
the parameter name songs when adding the description.

lib/catalog/getCatalogSongs.ts (1)

28-34: Complete the JSDoc parameter descriptions.

All four @param tags lack descriptions. Effective documentation should explain each parameter's purpose, especially for optional parameters like artistName and parameters with default values.

📝 Suggested JSDoc improvement

 /**
- *
- * `@param` catalogId
- * `@param` pageSize
- * `@param` page
- * `@param` artistName
+ * Fetches a single page of songs from a catalog
+ *
+ * `@param` catalogId - The unique identifier of the catalog
+ * `@param` pageSize - Number of songs per page (default: 100)
+ * `@param` page - Page number to fetch (default: 1)
+ * `@param` artistName - Optional filter to fetch songs by a specific artist
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/catalog/getCatalogSongs.ts` around lines 28 - 34, Update the JSDoc for
getCatalogSongs to provide meaningful descriptions for each `@param`: describe
catalogId as the identifier of the catalog to query (string), pageSize as the
number of songs to return per page (number, default value if applicable), page
as the 1-based page index to fetch (number, default if applicable), and
artistName as an optional filter to limit results to a specific artist (string,
optional). Mention default values and optionality where applicable so callers
understand behavior and which parameters can be omitted.

lib/catalog/getCatalogDataAsCSV.ts (1)

6-7: Complete the JSDoc parameter description.

The @param catalogId tag lacks a description. Document what the catalog ID represents to help developers understand the function's requirements.

📝 Suggested JSDoc improvement

 /**
  * Gets all catalog songs and formats them as CSV for the scorer
  *
- * `@param` catalogId
+ * `@param` catalogId - The unique identifier of the catalog to fetch and format
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/catalog/getCatalogDataAsCSV.ts` around lines 6 - 7, Add a clear JSDoc
description for the catalogId parameter in the getCatalogDataAsCSV function:
explain that catalogId is the unique identifier (string or numeric ID) of the
catalog whose data will be exported to CSV, whether it must be a UUID or
database primary key, and note any validation/format expectations (e.g.,
non-empty string). Update the `@param` tag for catalogId in the
getCatalogDataAsCSV JSDoc accordingly so callers know what value to pass.

lib/supabase/storage/uploadFileByKey.ts (1)

6-11: Enhance JSDoc with types and descriptions.

The @param entries list parameter names but lack type information and descriptions, which reduces their utility for developers and IDE intellisense. Standard JSDoc format includes both:

`@param` {string} key - The storage key/path for the uploaded file
`@param` {File | Blob} file - The file content to upload
`@param` {object} [options] - Upload options
`@param` {string} [options.contentType] - MIME type of the file (defaults to "application/octet-stream")
`@param` {boolean} [options.upsert] - Whether to overwrite existing files (defaults to false)

📝 Proposed JSDoc enhancement

 /**
  * Upload file to Supabase storage by key
  *
- * `@param` key
- * `@param` file
- * `@param` options
- * `@param` options.contentType
- * `@param` options.upsert
+ * `@param` {string} key - The storage key/path for the uploaded file
+ * `@param` {File | Blob} file - The file content to upload
+ * `@param` {object} [options] - Upload options
+ * `@param` {string} [options.contentType] - MIME type of the file (defaults to "application/octet-stream")
+ * `@param` {boolean} [options.upsert] - Whether to overwrite existing files (defaults to false)
+ * `@returns` {Promise<void>}
+ * `@throws` {Error} When upload fails
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/supabase/storage/uploadFileByKey.ts` around lines 6 - 11, Update the
JSDoc for the uploadFileByKey function to include types and short descriptions
for each parameter: document key as `@param` {string} key - The storage key/path
for the uploaded file; file as `@param` {File|Blob} file - The file content to
upload; options as `@param` {object} [options] - Upload options;
options.contentType as `@param` {string} [options.contentType] - MIME type of the
file (defaults to "application/octet-stream"); and options.upsert as `@param`
{boolean} [options.upsert] - Whether to overwrite existing files (defaults to
false); keep the JSDoc block above the uploadFileByKey declaration so IDEs can
pick up the types and defaults.

lib/spotify/getSpotifyFollowers.ts (1)

57-61: Consider documenting the first-result assumption.

The function returns follower count from the first search result without verifying it's the intended artist. For artists with common names or similar-sounding artists, this could return data for the wrong artist. Consider either:

• Adding a JSDoc note that the function returns the most relevant match
• Or adding validation logic to improve match confidence

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/spotify/getSpotifyFollowers.ts` around lines 57 - 61, The
getSpotifyFollowers function currently returns followers from
data.artists.items[0] without ensuring that item is the intended artist; update
the code or docs: either add a JSDoc comment on getSpotifyFollowers stating it
returns the most relevant (first) search match, or implement simple validation
before returning (e.g., compare artistName normalized/case-insensitive against
data.artists.items[0].name, optionally fall back to searching items for an exact
match or returning null/error if no confident match). Reference
data.artists.items[0] and the getSpotifyFollowers function when making the
change.

lib/content/getArtistContentReadiness.ts (2)

78-126: Optional: Consolidate file checks into a declarative structure.

The six file-checking blocks follow a repetitive pattern. Consider refactoring to a data-driven approach for improved maintainability:

♻️ Example declarative refactor

const fileChecks = [
  {
    check: () => hasFile("context/images/face-guide.png"),
    file: "context/images/face-guide.png",
    severity: "required" as const,
    fix: "Generate a face guide image before creating content.",
  },
  {
    check: () => hasFile("config/content-creation/config.json"),
    file: "config/content-creation/config.json",
    severity: "recommended" as const,
    fix: "Add a pipeline config to override default model/resolution settings.",
  },
  {
    check: () => hasAnyMp3,
    file: "songs/*.mp3",
    severity: "required" as const,
    fix: "Add at least one .mp3 file for audio selection.",
  },
  // ... remaining checks
];

const issues = fileChecks
  .filter(check => !check.check())
  .map(({ file, severity, fix }) => ({ file, severity, fix }));

This approach reduces duplication, makes adding new file checks trivial, and aligns with the DRY principle.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/getArtistContentReadiness.ts` around lines 78 - 126, The repeated
if-blocks performing file presence checks (using hasFile and hasAnyMp3) should
be replaced with a declarative array of check descriptors and a single
filter/map pipeline to populate the issues array; create a fileChecks array of
objects each containing a check function (or boolean), file, severity, and fix,
then set issues = fileChecks.filter(c => !c.check()).map(({file,severity,fix})
=> ({file,severity,fix})); update references to hasFile and hasAnyMp3 inside
those descriptors and remove the duplicated if blocks so adding or changing
checks is just editing the fileChecks entries.

---

31-138: Consider splitting this function to meet the 50-line guideline.

The getArtistContentReadiness function currently spans ~107 lines, exceeding the coding guideline of "Keep functions under 50 lines." While the logic is clear, breaking it into smaller, focused functions would improve maintainability and testability.

Consider extracting:

• File tree validation logic into a separate function
• The file-checking rules into a data-driven configuration
• Issue categorization and result building into helper functions

This refactor would align with both the 50-line guideline and Single Responsibility Principle at the function level. As per coding guidelines, "Keep functions under 50 lines" for domain functions in lib/**/*.ts.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/content/getArtistContentReadiness.ts` around lines 31 - 138, Split
getArtistContentReadiness into smaller helpers: extract the repo/tree validation
into a function (e.g., validateRepoAndTree that calls selectAccountSnapshots and
getArtistFileTree and returns githubRepo and blobPaths or early-not-ready
response), move path-check logic into a helper that builds issues from a
data-driven list (e.g., buildFileChecks or collectIssues that uses
getArtistRootPrefix and implements hasFile/hasAnyMp3 checks), and extract the
final categorization/response construction into a buildReadinessResult helper
that computes requiredMissing, warnings and returns the final object; keep
getArtistContentReadiness as an orchestration function that calls
validateRepoAndTree, collectIssues, and buildReadinessResult so each function
stays under ~50 lines and names like getArtistContentReadiness,
validateRepoAndTree, collectIssues/buildFileChecks, and buildReadinessResult
appear in the diff for easy location.

lib/prompts/getSystemPrompt.ts (1)

40-129: Consider using array-based string composition for cleaner code.

The current pattern of systemPrompt = \${systemPrompt}${section}`` works but could be simplified. Consider building sections in an array and joining them, which can improve readability and make testing individual sections easier.

💡 Alternative approach

const sections = [SYSTEM_PROMPT + /* base prompt content */];

if (accountWithDetails) {
  sections.push(buildUserContextSection(accountWithDetails, email));
}

if (artistInstruction) {
  sections.push(buildArtistInstructionSection(artistInstruction));
}

if (knowledgeBaseText) {
  sections.push(buildKnowledgeBaseSection(knowledgeBaseText));
}

return sections.join('\n');

This pairs well with the earlier suggestion to extract section-building logic into separate functions.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/prompts/getSystemPrompt.ts` around lines 40 - 129, The prompt-building
code repeatedly mutates systemPrompt by concatenating sections; refactor to
build an array of sections and join them to improve readability and testability:
create a sections array seeded with SYSTEM_PROMPT and the IMAGE
EDITING/IMPORTANT CONTEXT block, then replace the repeated `systemPrompt =
\`${systemPrompt}${...}\`` logic by pushing sections for accountWithDetails (use
a helper like buildUserContextSection to assemble the userSection using
accountWithDetails and email), artistInstruction
(buildArtistInstructionSection), and knowledgeBaseText
(buildKnowledgeBaseSection), and finally set systemPrompt = sections.join('\n');
ensure existing identifiers systemPrompt, accountWithDetails, artistInstruction,
knowledgeBaseText, and the userSection construction are used to locate and
replace the current concatenation logic.

lib/admins/privy/countNewAccounts.ts (1)

9-10: Align parameter docs with project terminology.

Please avoid users in docs and prefer accounts (or a specific subtype) to match repo language conventions.

As per coding guidelines "**/*.{ts,tsx}: Use 'account' terminology, never 'entity' or 'user'; use specific names like 'artist', 'workspace', 'organization' when referring to specific types".

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/admins/privy/countNewAccounts.ts` around lines 9 - 10, Update the JSDoc
param name to use the project's preferred terminology: replace the `@param` tag
that currently says "users" with "accounts" (or a more specific subtype if
applicable) in the documentation for the countNewAccounts function so the docs
match the repo convention; ensure any inline references in the comment block to
"users" are renamed to "accounts" (or e.g., "artist", "workspace",
"organization" if that more accurately describes the input) while leaving the
function and implementation unchanged.

app/api/accounts/[id]/route.ts (1)

26-27: Clarify destructured params in JSDoc.

@param params.params is ambiguous. Prefer documenting the destructured argument once (e.g., @param context - Route context containing params.id) to avoid confusion.

Suggested doc cleanup

- * `@param` params.params
- * `@param` params - Route params containing the account ID
+ * `@param` context - Route context containing params.id (account UUID)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/accounts/`[id]/route.ts around lines 26 - 27, Update the JSDoc for
the route handler to remove the ambiguous "@param params.params" and document
the destructured parameter once; e.g., replace the two entries with a single
line like "@param context - Route context containing params.id (the account ID)"
and, if the handler destructures params (e.g., function handler({ params }) or
function GET(context)), mention that params.id is the account identifier so
readers know which property is used (reference params and params.id in the
comment).

lib/admins/privy/fetchPrivyLogins.ts (1)

23-26: Consolidate duplicated JSDoc into a single function-level block.

This new placeholder doc is too thin and, combined with the earlier block, leaves docs split across the type alias and function. Prefer one complete JSDoc directly above fetchPrivyLogins for clarity and DRYness.

♻️ Suggested doc cleanup

-/**
- * Fetches Privy users active or created within the given period via the Privy Management API.
- * Returns the full, unmodified user objects from Privy.
- * Paginates through all users, collecting those whose created_at or latest_verified_at
- * falls within the time window.
- *
- * `@see` https://docs.privy.io/api-reference/users/get-all
- * `@param` period - "daily", "weekly", or "monthly"
- * `@returns` Array of full Privy user objects within the time window, sorted by created_at descending
- */
 export type FetchPrivyLoginsResult = {
   users: User[];
   totalPrivyUsers: number;
 };
 
 /**
- *
- * `@param` period
+ * Fetches Privy users active or created within the given period via the Privy Management API.
+ * Returns full user objects from Privy and total user count seen during pagination.
+ *
+ * `@see` https://docs.privy.io/api-reference/users/get-all
+ * `@param` period - "all", "daily", "weekly", or "monthly"
+ * `@returns` Users in window (sorted by created_at desc) and totalPrivyUsers
  */
 export async function fetchPrivyLogins(period: PrivyLoginsPeriod): Promise<FetchPrivyLoginsResult> {

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/admins/privy/fetchPrivyLogins.ts` around lines 23 - 26, Consolidate the
duplicated JSDoc by removing the thin/placeholder block currently above the type
alias and create one complete JSDoc directly above the fetchPrivyLogins function
describing its parameters (e.g., period), return value, and behavior; ensure the
JSDoc fully documents fetchPrivyLogins (and remove the separate doc on the type
alias) so all documentation is single-source and immediately precedes the
fetchPrivyLogins declaration.

lib/artistIntel/getArtistMusicAnalysis.ts (1)

29-40: Generation parameters are overridden by preset config.

Per processAnalyzeMusicRequest implementation, when a preset is provided, the preset's own parameters (max_new_tokens, temperature, do_sample) are extracted from the preset config and override any values passed here. The top_p is also set to undefined for presets.

These hardcoded values (lines 34-37) are effectively dead code and may mislead future maintainers into thinking they control the generation behavior. Consider removing them for clarity:

♻️ Suggested simplification

     ANALYSIS_PRESETS.map(preset =>
       processAnalyzeMusicRequest({
         preset,
         audio_url: previewUrl,
-        max_new_tokens: 512,
-        temperature: 1.0,
-        top_p: 1.0,
-        do_sample: false,
       }),
     ),

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/artistIntel/getArtistMusicAnalysis.ts` around lines 29 - 40, The
generation params passed into processAnalyzeMusicRequest are shadowed by the
provided preset, so remove the dead hardcoded options (max_new_tokens,
temperature, top_p, do_sample) from the ANALYSIS_PRESETS.map call and only pass
the preset and audio_url (and any truly dynamic args); update the map invocation
that calls processAnalyzeMusicRequest(preset, audio_url, ...) to call
processAnalyzeMusicRequest({ preset, audio_url }) so the preset-driven config is
used and future maintainers aren’t misled by ineffective overrides.

app/api/admins/privy/route.ts (1)

18-20: Empty JSDoc for OPTIONS handler.

The OPTIONS handler should document its CORS preflight purpose:

📝 Suggested improvement

 /**
- *
+ * OPTIONS /api/admins/privy
+ *
+ * CORS preflight handler returning appropriate headers.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/admins/privy/route.ts` around lines 18 - 20, The empty JSDoc above
the OPTIONS handler should be replaced with a short descriptive comment that
documents this handler's role as the CORS preflight responder: update the JSDoc
for the OPTIONS function (the OPTIONS handler in app/api/admins/privy/route.ts)
to state it handles CORS preflight requests, lists the allowed methods and
headers it responds with (e.g., Access-Control-Allow-Methods,
Access-Control-Allow-Headers, Access-Control-Allow-Origin), and notes it returns
a 204/OK empty response for preflight checks so future readers understand its
purpose.

app/api/transcribe/route.ts (1)

5-8: Empty JSDoc provides no value.

The JSDoc block has an empty description and @param req without any explanation. Per the coding guidelines, API routes should have meaningful JSDoc comments that describe the endpoint's purpose, expected inputs, and responses.

Consider documenting what this endpoint does:

📝 Suggested improvement

 /**
- *
- * `@param` req
+ * POST /api/transcribe
+ *
+ * Transcribes audio files using OpenAI Whisper and saves both the original
+ * audio and transcript markdown to the artist's files.
+ *
+ * `@param` req - Request containing audio_url, account_id, artist_account_id, title, and include_timestamps.
+ * `@returns` Transcription result with audio file, transcript file, text, and language.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@app/api/transcribe/route.ts` around lines 5 - 8, Replace the empty JSDoc
above the API route handler with a meaningful comment: describe the endpoint's
purpose, the expected request shape (e.g., multipart/form-data or JSON,
file/audio format, and any required fields in req), the returned response
structure and status codes, and document the req parameter (e.g., Request) and
what it should contain; update the JSDoc immediately above the route handler
function (the POST handler/exported route in route.ts) to include these details
and remove the blank `@param` entry so the comment provides clear API usage and
expectations.

lib/mcp/resolveAccountId.ts (1)

18-21: JSDoc param annotations lack descriptions.

The nested @param tags would be more helpful with brief descriptions:

📝 Suggested improvement

  * `@param` params - The auth info and optional account_id override.
- * `@param` params.authInfo
- * `@param` params.accountIdOverride
+ * `@param` params.authInfo - MCP authentication info from the request.
+ * `@param` params.accountIdOverride - Optional account_id to use instead of authenticated account.
  * `@returns` The resolved accountId or an error message.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/resolveAccountId.ts` around lines 18 - 21, Update the JSDoc for
resolveAccountId to add brief descriptions for the nested parameters: describe
params as the input object containing auth info and optional override, document
params.authInfo (e.g., the authentication object containing user/org identifiers
or tokens used for resolution), and document params.accountIdOverride (e.g.,
optional string to force a specific accountId). Also ensure the `@returns` line
briefly explains the resolved accountId or an error message format so callers
know what to expect.

lib/mcp/tools/transcribe/registerTranscribeAudioTool.ts (1)

18-21: Empty JSDoc provides no documentation value.

The JSDoc block has an empty description and @param server without explanation. Consider providing meaningful documentation:

📝 Suggested improvement

 /**
- *
- * `@param` server
+ * Registers the `transcribe_audio` MCP tool for audio transcription via OpenAI Whisper.
+ *
+ * `@param` server - The MCP server instance to register the tool on.
  */

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/transcribe/registerTranscribeAudioTool.ts` around lines 18 -
21, The JSDoc above the registerTranscribeAudioTool function is empty and
unhelpful; replace it with a concise description of what
registerTranscribeAudioTool does and document the parameter `server` (its type
or expected interface and role) and any return value or side effects; update the
comment block near the registerTranscribeAudioTool declaration in
registerTranscribeAudioTool.ts to include a one-line summary, `@param server`
explanation, and `@returns` or `@throws` if applicable so IDEs and readers get
meaningful documentation.

lib/artistIntel/buildArtistMarketingCopy.ts (2)

63-66: Consider validating AI response structure with Zod.

The JSON.parse(result.text) result is cast directly to ArtistMarketingCopy without runtime validation. AI models can return malformed JSON, missing fields, or unexpected structures. Adding Zod validation would provide type safety and clearer error handling:

♻️ Suggested improvement

+import { z } from "zod";
+
+const ArtistMarketingCopySchema = z.object({
+  playlist_pitch_email: z.string(),
+  instagram_caption: z.string(),
+  tiktok_caption: z.string(),
+  twitter_post: z.string(),
+  press_release_opener: z.string(),
+  key_talking_points: z.array(z.string()),
+});
+
 // In the try block:
   try {
     const result = await generateText({ system: SYSTEM_PROMPT, prompt });
-    const parsed = JSON.parse(result.text) as ArtistMarketingCopy;
-    return parsed;
+    const parsed = ArtistMarketingCopySchema.parse(JSON.parse(result.text));
+    return parsed;
   } catch (error) {

This aligns with the codebase pattern of using Zod for input/output validation.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/artistIntel/buildArtistMarketingCopy.ts` around lines 63 - 66, The code
in buildArtistMarketingCopy calls generateText and directly casts
JSON.parse(result.text) to ArtistMarketingCopy; add runtime validation using a
Zod schema (e.g., define/import ArtistMarketingCopySchema) to parse and validate
the parsed object instead of a direct cast, catching Zod or JSON errors and
returning/throwing a clear error with context (include result.text) from the
buildArtistMarketingCopy function so malformed AI responses are detected and
handled safely.

---

34-35: Guard against empty topTracks array.

If topTracks is an empty array, topTracks[0] will be undefined. While the optional chaining on topTrack?.name handles this downstream, adding an explicit check improves readability:

♻️ Minor clarity improvement

   const { artist, topTracks } = spotifyData;
-  const topTrack = topTracks[0];
+  const topTrack = topTracks.length > 0 ? topTracks[0] : undefined;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/artistIntel/buildArtistMarketingCopy.ts` around lines 34 - 35, The code
grabs topTracks from spotifyData and directly indexes topTracks[0] into topTrack
which can be undefined when topTracks is an empty array; update the
buildArtistMarketingCopy logic to explicitly guard for an empty topTracks (e.g.,
compute topTrack = Array.isArray(topTracks) && topTracks.length > 0 ?
topTracks[0] : null) and use that guarded value wherever topTrack is referenced
so downstream optional chaining remains clear and the intent is explicit
(referencing symbols: spotifyData, topTracks, topTrack,
buildArtistMarketingCopy).

lib/mcp/tools/artistIntel/registerGenerateArtistIntelPackTool.ts (1)

11-16: Share the artist_name schema with API validation to prevent drift.

This schema duplicates lib/artistIntel/validateArtistIntelBody.ts; any future change can desync MCP vs API behavior.

♻️ Suggested refactor

-const toolSchema = z.object({
-  artist_name: z
-    .string()
-    .min(1)
-    .describe("The artist name to analyze (e.g. 'Taylor Swift', 'Bad Bunny', 'Olivia Rodrigo')."),
-});
+import { artistIntelBodySchema } from "@/lib/artistIntel/artistIntelSchema";
+
+const toolSchema = artistIntelBodySchema;

Create lib/artistIntel/artistIntelSchema.ts as the shared source of truth, then import it in both MCP and API validators.

As per coding guidelines **/*.{ts,tsx}: Extract shared logic into reusable utilities following Don't Repeat Yourself (DRY) principle.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/mcp/tools/artistIntel/registerGenerateArtistIntelPackTool.ts` around
lines 11 - 16, The toolSchema definition duplicates the API validator; extract
the shared schema into a new module (e.g., export a zod schema from
lib/artistIntel/artistIntelSchema.ts) and replace the local const toolSchema
here with an import of that shared schema (preserving the artist_name field
constraints), and update lib/artistIntel/validateArtistIntelBody.ts to import
the same symbol so both MCP (registerGenerateArtistIntelPackTool -> toolSchema /
artist_name) and the API use the single source of truth.

lib/artistIntel/getArtistSpotifyData.ts (1)

5-23: Use shared Spotify types instead of local duplicates.

These local interfaces will drift from the canonical Spotify types and duplicate maintenance effort.

As per coding guidelines **/*.{ts,tsx}: Extract shared logic into reusable utilities following Don't Repeat Yourself (DRY) principle.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/artistIntel/getArtistSpotifyData.ts` around lines 5 - 23, The file
defines local duplicate interfaces SpotifyArtist and SpotifyTrack which should
be replaced with the project's shared Spotify types to avoid drift; remove these
local interfaces from getArtistSpotifyData.ts and import the canonical types
(e.g., SpotifyArtist, SpotifyTrack or equivalent) from the shared types module
used across the repo (check modules like types/spotify, shared/types, or
src/types) and update any references in getArtistSpotifyData and related
functions to use the imported types so the code relies on the single source of
truth.

lib/artistIntel/getArtistWebContext.ts (1)

20-27: ⚠️ Potential issue | 🟠 Major

Replace fixed “2024-2025” range with dynamic years.

At Line 22, the prompt hard-codes 2024-2025. On March 21, 2026, this biases results away from 2026 coverage and can degrade “current/recent” context quality.

Suggested fix

 export async function getArtistWebContext(artistName: string): Promise<ArtistWebContext | null> {
   try {
+    const currentYear = new Date().getUTCFullYear();
+    const previousYear = currentYear - 1;
     const result = await chatWithPerplexity([
       {
         role: "user",
         content: `Research the music artist "${artistName}". Provide a concise but rich overview covering:
 1. Who they are and their current career stage
-2. Recent releases, streaming milestones, or news (2024-2025)
+2. Recent releases, streaming milestones, or news (${previousYear}-${currentYear})
 3. Their core sound and genre positioning
 4. Notable collaborations, press coverage, or cultural moments
 5. Why they matter right now in the music industry

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/artistIntel/getArtistWebContext.ts` around lines 20 - 27, The prompt in
getArtistWebContext.ts hard-codes the year range "2024-2025" in the content
template, which will become stale; update the template in the content field used
by getArtistWebContext to compute the current year dynamically (e.g., const
currentYear = new Date().getFullYear() and previousYear = currentYear - 1) and
inject those values into the prompt string instead of the fixed "2024-2025" text
so the “current/recent” range always reflects the present year.

lib/artistIntel/buildArtistMarketingCopy.ts (2)

37-114: Function exceeds 50-line guideline; consider extracting helpers.

The function spans ~78 lines, violating the coding guideline to "Keep functions under 50 lines." The responsibilities—prompt construction, AI invocation, response parsing, and fallback generation—could be split for improved testability and adherence to Single Responsibility Principle.

As per coding guidelines: "Keep functions under 50 lines."

♻️ Suggested decomposition

// Helper: build the AI prompt
function buildMarketingPrompt(
  artist: SpotifyArtist,
  topTrack: SpotifyTrack | null,
  musicAnalysis: ArtistMusicAnalysis | null,
  webContext: ArtistWebContext | null,
): string {
  // ... prompt template logic (~40 lines)
}

// Helper: generate fallback copy
function buildFallbackMarketingCopy(
  artist: SpotifyArtist,
  topTrack: SpotifyTrack | null,
): ArtistMarketingCopy {
  // ... fallback object construction (~25 lines)
}

// Main function stays lean
export async function buildArtistMarketingCopy(...): Promise<ArtistMarketingCopy> {
  const { artist, topTracks } = spotifyData;
  const topTrack = topTracks[0] ?? null;
  const prompt = buildMarketingPrompt(artist, topTrack, musicAnalysis, webContext);
  
  try {
    const result = await generateText({ system: SYSTEM_PROMPT, prompt });
    // ... parse and return
  } catch (error) {
    console.error("Failed to generate marketing copy:", error);
    return buildFallbackMarketingCopy(artist, topTrack);
  }
}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/artistIntel/buildArtistMarketingCopy.ts` around lines 37 - 114, The
function buildArtistMarketingCopy is too long and mixes responsibilities (prompt
construction, AI call, parsing, fallback); extract a helper
buildMarketingPrompt(artist, topTrack, musicAnalysis, webContext) to return the
long prompt string and another helper buildFallbackMarketingCopy(artist,
topTrack) to construct the fallback ArtistMarketingCopy object, then simplify
buildArtistMarketingCopy to assemble topTrack, call buildMarketingPrompt, await
generateText({ system: SYSTEM_PROMPT, prompt }), JSON.parse the result, and on
catch call buildFallbackMarketingCopy while preserving the existing logging
behavior; keep signature and return types the same.

---

42-43: Consider explicit guard for empty topTracks array.

Per getArtistSpotifyData.ts (line 61), topTracks can be an empty array when the track fetch fails. While the downstream optional chaining (topTrack?.name) prevents runtime errors, an explicit guard improves readability and intent.

♻️ Suggested improvement

 const { artist, topTracks } = spotifyData;
-const topTrack = topTracks[0];
+const topTrack = topTracks.length > 0 ? topTracks[0] : null;

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/artistIntel/buildArtistMarketingCopy.ts` around lines 42 - 43, Replace
the direct indexing of topTracks with an explicit guard: instead of const
topTrack = topTracks[0]; check that topTracks is an array and has length > 0
(e.g., if (!Array.isArray(topTracks) || topTracks.length === 0) { /* handle
missing topTrack: set topTrack = undefined or return/compose fallback marketing
copy */ }) and then safely assign topTrack when present; update
buildArtistMarketingCopy's logic where topTrack is used to rely on this clear
guard (symbols: topTracks, topTrack, buildArtistMarketingCopy).

lib/artistIntel/computeArtistOpportunityScores.ts (1)

46-274: Split the four scoring models into private helpers.

computeArtistOpportunityScores() now owns four separate heuristics, rationale assembly, clamping, and weighting in one body, which makes threshold changes hard to test or reason about safely. Extract per-domain calculators and keep this exported function focused on composition. As per coding guidelines, lib/**/*.ts: “Single responsibility per function”, “Keep functions under 50 lines”, and “DRY: Consolidate similar logic into shared utilities”.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@lib/artistIntel/computeArtistOpportunityScores.ts` around lines 46 - 274,
computeArtistOpportunityScores is doing four distinct heuristics in one large
function; extract each domain into a private helper to improve testability and
single responsibility. Create four helpers (e.g., computeSyncScore,
computePlaylistScore, computeArScore, computeBrandScore) that accept the
relevant inputs (musicAnalysis/meta, followers, popularity, peerBenchmark) and
return a consistent shape like { score: number, rationale: string[] }; move
domain-specific clamping/rating logic into either each helper or a small shared
utility (e.g., clampTo100, buildRationale) so duplicate min/max/rationale joins
are removed; then refactor computeArtistOpportunityScores to call those helpers,
compute the weighted overall, and return the same public shape using rating(...)
and joined rationales. Ensure helper names match the ones above to make locating
code straightforward and keep each function under ~50 lines.